fix onboarding runtime validation and first-start routing - #444

分诊（2026-07-29，通信龙）：建议保留并 rebase，优先级高。

本 PR 与今天的两个 P0 高度重叠，而且部分工作今天被独立重做了一遍：

• 「declare and enforce the Bun prerequisite before Hub startup」—— 今天的新人视角走查发现，照 README 复制代码块跑会崩 spawn bunx ENOENT。我只改了文档位置（docs: Bun 前置提到快速上手代码块之前（新人第一步就崩） #484 已合），本 PR 是在代码里强制检查，比我做得彻底。
• 「reject unknown explicit and persisted runtimes instead of silently falling back」—— 这正是 issue [latest] agent-node 对 --runtime 不做校验：任意字符串（含 bogus-xyz）均被接受并静默退化 #478 的内容（当前填一个不存在的 runtime 也照收）。

当前状态：CONFLICTING / DIRTY，需 rebase 到 origin/main。冲突大概率来自今天合入的 #484（README）与 #483 / #489（cli.ts）。

这条是「陈旧 PR 腐烂」的活样本：它躺了两周没人合，期间我们从零重新发现并修复了它已经修过的问题。每多躺一天，冲突只会更多，而重复劳动已经发生过一次。

建议：确认 owner → rebase → 走正常复核。若判断已被今天的改动完全覆盖而无需保留，也请明确关闭并说明理由，不要继续挂着腐烂。

分流结论:实质已落地,只有测试没进来 —— 和 #436 同一形状。不关,归属作者。

逐条核(取自 origin/main):

① Bun 前置强制        ✅ 已落地,而且是真强制不是警告
   agent-network/bin/cli.ts:5665
     if (!commandExists("bunx") && !commandExists("bun")) {
       ❌ anet hub start requires the Bun runtime …
       process.exit(1);

② npx agent-node@preview fallback   ✅ 已落地(cli.ts 里 10 处)

③ normalize-runtime.ts              ✅ 在 main 上

没进来的只有两个测试文件:

agent-network/src/onboarding-guards.test.ts     不在 main
agent-network/src/onboarding-cli-smoke.test.ts  不在 main

也就是说这三项行为现在靠实现自身正确,没有测试钉住。
behind=422,整支 rebase 代价大;建议只把这两个测试摘到当前 main 上开一个小 PR ——
它们要断言的行为已经存在,应该能直接跑。

归属在你,我不替你关。

更正:我上一条给的建议是错的

我上一条说「只把这两个测试摘到当前 main 开一个小 PR —— 它们要断言的行为已经存在,应该能直接跑」。
这句话不成立,我实际试过之后才发现:

onboarding-guards.test.ts   import { … } from "./onboarding-guards"
                            ← onboarding-guards.ts 是本 PR 新增的源模块,不在 main 上
main 的 cli.ts 里 runtimeUsesAgentNode / parseExplicitRuntime /
bunHubPrerequisiteIssue 三个符号命中 0  ← 逻辑还是内联在 cli.ts 里

所以那一半根本不可摘,它依赖的是本 PR 的重构(把 cli.ts 的逻辑抽成可测函数)。

另一半我真跑了,结果是 6 pass / 7 fail

onboarding-cli-smoke.test.ts 只依赖 bun:test + node 内置,可以摘。我把它取到当前 main 上跑:

6 pass / 7 fail / 35 expect

⚠️ 第一次我跑出 13 全红,那个结果是无效的 —— 当时 worktree 里没装依赖,
CLI 起不来(Cannot find module '@inquirer/prompts'),13 条红全是环境缺口,
一条都不能当结论。装好依赖后才是上面这个数。

7 条不通过的,主要是两类

(a) 退出码语义:本 PR 期望 exitCode === 2 用来区分「校验失败」,main 上是 1 或 0。

unknown --runtime exits non-zero before Hub access   Expected 2, Received 1
batch custom unknown --runtime exits 2               Expected 2, Received 1
unknown stored runtime exits 2                       Expected 2, Received 0

注意 Received: 1 说明拒绝是存在的,只是没有独立的退出码;
但 Received: 0 那条不一样 —— 那是真的没拒。

(b) anet -v 不声明 Bun 前置。main 上 anet -v 的输出是:

Optional runtimes (install only what you'll use):
  ○ claude CLI — only needed for the claude-code-cli runtime
  ○ codex CLI  — only needed for the codex-sdk runtime

只列了可选运行时,完全没提 Bun —— 而 anet hub start 对 Bun 是硬要求
(cli.ts:5665,process.exit(1))。也就是说这个唯一的硬前置在自报信息里是隐形的,
用户要撞上去才知道。(文档侧已经在 #720 写清了三条前置链,但 CLI 自报没跟上。)

所以建议改成

1. onboarding-cli-smoke.test.ts 里已经通过的那 6 条可以先摘过来 —— 它们是现成的回归保护;
2. 退出码那 3 条是产品决策(要不要给校验失败一个独立退出码),不是能靠摘文件解决的;
   其中 Received: 0 那条值得单独看,它可能是真缺口;
3. onboarding-guards.test.ts 要等重构一起走,摘不动。

我没有替你动这个 PR。上面的数字都可复跑:worktree 起在 origin/main,
cd agent-network && npm install,再 bun test src/onboarding-cli-smoke.test.ts。

2026-08-13 maintenance triage: CLOSE AS SUPERSEDED / DO-NOT-MERGE; preserve branch and evidence.

The original onboarding concerns have since moved into current-main implementations with different structure: execution boundaries use normalizeRuntimeStrict, first agent-node launch has the @sleep2agi/agent-node@preview fallback, and Bun prerequisites are now documented/checked under the later pinned-install discipline. This old branch is not a safe delta to revive: it advertises only six runtimes while current main supports seven (including grok-build-cli), its Bun guidance still points at curl ... bun.sh, and it predates the later vendor registry, daemon, opencode/grok launch, and supply-chain gates.

The branch also remains a broad 10-file historical patch against July main. Any still-reproducible onboarding defect must be filed/reproduced against current main and fixed narrowly; it must not be inferred from this stale branch or solved by merging it wholesale. Immutable head 91e0b85d and its report remain available for history. No branch deletion, product change, package release, or production action.